Modifier Reference
Table of contents
- Introduction
- 3D Coordinates
- 8-way direction
- Canvas coordinates
- Curve
- Deadzone
- Input swizzle
- Map Range
- Negate
- Normalize
- Positive/Negative
- Scale
- Virtual Cursor (experimental)
- Window relative
Introduction
G.U.I.D.E ships with a selection of modifiers for many use cases. This is a list of all built-in modifiers and their configuration settings:
3D Coordinates
This modifier converts a 2D mouse position (from the Mouse Position input) into 3D world coordinates. It does this by performing a raycast into the game world using the currently active 3D camera. Use this to find out “where in my 3D world did the player just click”. It has the following settings:
Setting | Description |
---|---|
Max Depth | The maximum depth for the ray cast in units. |
Collide with areas | Whether the raycast should collide with areas. |
Collision mask | A mask used for the ray cast. This should be set up so the collision layers that make up your “world” are selected for collision. |
The modifier sets the action value to the 3D world position of the raycast hit. If the raycast hits nothing, the
modifier sets the action value to Vector3.INF
.
8-way direction
This is a filtering modifier that checks whether 2D input points into one of 8 directions. If the input points into this
direction, sets the action value to (1,0,0)
otherwise to (0,0,0)
. Can be used to get discrete directions from analog
input. It has the following setings:
Setting | Description |
---|---|
Direction | The direction for which the modifier should filter. |
Canvas coordinates
This modifier converts a 2D pixel coordinate (from the Mouse Position, Touch Position or Touch Axis inputs) into 2D world coordinates (canvas coordinates) for the currently active viewport. This modifier takes into account the current scaling mode and any changes (zoom, offset) applied by a Camera2D in the currently active viewport. Use this to quickly find out “where in my 2D world did the player just click”. This modifier has the following settings:
Setting | Description |
---|---|
Relative Input | Whether the input is absolute or relative. |
Curve
This modifier applies a separate curve to each input axis. Input values are assumed to fall in the range of 0
to 1
.
You can use the Map Range modifier to convert your value into this range, if needed. It has the following settings:
Setting | Description |
---|---|
Curve | The curve to apply. |
X | Apply the modifier to the X axis |
Y | Apply the modifier to the Y axis |
Z | Apply the modifier to the Z axis |
Deadzone
This modifier applies a deadzone to 1D, 2D or 3D axis input. You can specify a minimum and maximum value. Every input outside the minimum and maximum will be clamped while all the values between the minimum and maximum will be scaled to a range between 0 and 1. This modifier has the following settings:
Setting | Description |
---|---|
Lower threshold | The lower threshold for the input. All values below this value will be mapped to 0. |
Upper threshold | The upper threshold for the input. All values above this value will be mapped to 1. |
Input swizzle
This modifier rearranges the x,y and z components of the current input value. This is useful if you want to bind keys to multiple axes or otherwise want to modify the input vector to do any operations on it. This modifier is often combined with the Negate modifier. It has the following settings:
Setting | Description |
---|---|
Order | The new order of the input vector. |
Map Range
This modifier maps the input value through an input and output range and optionally clamps the output. Can be used to
scale and translate at the same time. (For example, mapping a 0
to 1
range to a -1
to 1
range.) It has the
following settings:
Setting | Description |
---|---|
Apply clamp | Whether the output should be clamped to the output range. |
Input min | The input minimum. |
Input max | The input maximum. |
Output min | The output minimum. |
Output max | The output maximum. |
X | Apply the modifier to the X axis |
Y | Apply the modifier to the Y axis |
Z | Apply the modifier to the Z axis |
Negate
This modifier negates one or more axes of the input vector. Useful to map key inputs to negative values or to realize inverted controls for joysticks. It has the following settings:
Setting | Description |
---|---|
X | Whether the x -axis of the input should be negated. |
Y | Whether the y -axis of the input should be negated. |
Z | Whether the z -axis of the input should be negated. |
Normalize
This modifier normalizes the input vector (e.g. keeps the direction but changes the length to 1). It has no settings.
Positive/Negative
Limits inputs to positive or negative values. Values which do not match will be clamped to zero. Useful if you want to bind different halves of an axis to different actions. This modifier has the following settings:
Setting | Description |
---|---|
Range | Whether the the input should be limited to positive or negative values. |
X | Whether the x -axis of the input should be affected. |
Y | Whether the y -axis of the input should be affected. |
Z | Whether the z -axis of the input should be affected. |
Scale
Multiplies the input with the given Vector3. Useful to control things like input sensitivity or to convert input into a more useful range (e.g. radians from 0-1). Input can also be multiplied with delta time (to limit input over time). The modifier has the following settings:
Setting | Description |
---|---|
Scale | A Vector3 which is multiplied with the input vector. |
Apply delta time | If checked, the input is additionally multiplied with the current delta time. |
Virtual Cursor (experimental)
This modifier provides a virtual 2D cursor that can be controlled by any input. This is useful if you need to simulate mouse input with a controller. The input will be treated as a 2D vector that moves the cursor around. The cursor will be clamped to the window size. Output of this modifier is the cursor position in pixels (similiar to what the Mouse Position input returns). Use the 3D coordinates or Canvas coordinates modifier to convert the cursor position into 3D or 2D world coordinates. This modifier has the following settings:
Setting | Description |
---|---|
Initial position | The initial position of the cursor in a range between 0 and 1. This will be automatically scaled to the actual window size. |
Speed | The cursor movement speed in pixels. |
Screen Scale | Screen scaling to be applied to the cursor movement. This controls whether the cursor movement speed is resolution dependent. The following settings are possible: <ul><li>None - no scaling according to the screen resolution is done. An input of (1,1,0) will move the cursor one pixel down and one to the right.</li><li>Longer Axis - input will be scaled by the longer axis of the screen resolution (e.g. x-axis in landscape modes, y-axis in portrait modes).</li><li> Shorter Axis - Input will be scaled by the shorter axis of the screen resolution (e.g. y-axis in landscape modes, x-axis in portrait modes).</li></ul> |
Apply delta time | If checked, the input is additionally multiplied with the current delta time. |
Window relative
Treats the input vector as a mouse position difference in pixels (e.g. from the Mouse input) and converts it into a
range from (0,0)
to (1,1)
relative to the current window size. Useful to get resolution-independent mouse
differences. This modifier has no settings.
Note: Depending on the operating system and input device this modifier may not be required and will in fact make your input resolution-dependent when applied.
You already get resolution-independent values when:
- using the mouse running on Linux
- using the mouse running on OSX
- using the mouse running on Windows with the mouse cursor captured
In these cases, the modifier should not be applied.
You get resolution-dependent mouse values when:
- using the mouse running on Windows with the mouse cursor visible
- using touch input running on Android
In these cases the modifier can be applied. Other combinations have not been tested, so you may need to conduct your own research here and report your findings, so they can be added to the documentation.